    geocalInfor		package:nenhum		R Documentation
    
    Geographic distances calculator
    
    Description:
    
    Uma função simples que:
     
     (1). identifica unidad geográfica padrão mais próxima aos de pontos geográficos estudados, calculando as distâncias em Kms entre a base de dados de estudo e as unidades padrão.
     
     (2). Usando o valor de um caracter biologico amostrado (uma medição de algum rasgo dos individuos estudados) e as médias para esse caracter ("mean") para cada 'grupo geografico' da analise (1), são calculadas as diferencias das medias desse caracter (media de cada grupo identificado - o valor de cada individuo para esse caracter), e identifica o 'grupo geográfico' que tenha a minima diferencia na média, criando um novo set de grupos.
     
     (3). realiza um plot do mapa da area estudada (o shapefile deve ser derfinido pelo usurario) com os pontos de cada grupo identificado nos analises (1) e (2) para sua comparação.
    
    Usage:
    
      geocalInfor(x,loc_pattern)
      geocalInfor(x,loc_pattern,map=TRUE,save.map=FALSE)

    Arguments:

      x: objeto contendo uma planilha de três colunas no formato "*csv" ou "*txt".
      loc_pattern: o arquivo com os pontos geográficos pradrão (o nome do objeto deve ser exato!).
      map: além da matriz de distâncias gerada na função, plota os pontos (grupos de pontos) num mapa.
      save.map: salva o mapa em uma figura "pdf" #jpeg.

    Details:
      O argumento x (o arquivo 1) deve ser uma planilha com coordenadas em grau decimal. A planilha deve ter as distribuições geográficas estudadas, com 4 colunas com conteúdo obrigatório e ordenado: 
	Coluna 1: Nome ou identificação do indivíduo ou ponto. Coluna 2: dados de latitude ("Latitude"). 
	Coluna 2: dados da Longitude ("Longitude").
	Coluna 4: Os valor do caracter biolologico continuo (medição em metros/cms/mm, etc).
     
      Um arquivo 2, de nome "loc_pattern", tem as distribuições geográficas padrão (pré-definido pelo usuário), com três colunas de conteúdo obrigatório e ordenado: 
	Coluna 1: Nome dos pontos geográficos predefinidos (letras!).
	Coluna 2: dados da Latitude ("Latitude").
	Coluna 2: dados da Longitude ("Longitude").
         
      Para utilização do argumento "map" é necessário instalar o pacote maptools: http://cran.r-project.org/web/packages/maptools/index.html.
      
      Também é necessário que o usuário salve no diretório o shapelife (*"shp") que é usado na construção do mapa, nomeando-o dentro do código da função com o mesmo nome que está no diretório.
      
      Para a elaboração dos mapas, o usuario precisa reemplazar o nome da are segundo a área que quera comparar! see message:
	      ### in the MAP section, replace into command points() the groups thast you want plot! ###. as follow:
	      ## "list_geo$ X $Longitude" where X is a group to test ##
	      ## "list_geo$ X $Latitude" where X is a group to test ##

  Value:
    A função retorna uma tabela em formato texto com colunas com os nomes de cada ponto/individuo estudado e os grupos aos quais perteneces segundo os analises:
	
	"geo.groups" para os grupos da analise (1). 		"bio.groups" para a analise (2).
    
    A tabela é automaticamente salva no formato "*csv" no diretório que está sendo utilizado.
    
    Se o comando map=FALSE não é marcado, um mapa com os resultados será ploteado. 
    
    Se save.map=TRUE é marcado, a função também salva uma figura no formato "jpeg" (ou pdf, se o usuario quiser).

    Warning:
      
      Caso o objeto de entrada 2 não exista, uma mensagem de erro será dada pela função e esta será interrompida.
    
    Note:
      
      As distancias geográficas são calculadas usando a formula da Lei esférica dos cossenos ('Spherical law of cosines') http://en.wikipedia.org/wiki/Spherical_law_of_cosines.
      
      Os shapes para plot dos mapas podem ser baixados aqui: http://www.diva-gis.org/Data

      Author(s):

	Sergio David Bolívar

    References:

     http://cran.r-project.org/web/packages/maptools/index.html
     http://www.diva-gis.org/Data
     http://en.wikipedia.org/wiki/Spherical_law_of_cosines
     http://www.r-bloggers.com/great-circle-distance-calculations-in-r/
     
     
Examples:
     x<read.csv("loc_pontos.csv",header=T,sep="\t",dec=",")
     geocalInfor(x,map=FALSE) # Usando distancias geograficas e diferencias de médias; identifica os grupos mais proximos (geograficamente e quantitativamente) aos dados estudados e cria duas tabelas resultados desses analises.
     
     geocalInfor(x) #Cria as tabelas e o mapa(s) com os pontos.
          
     geocalInfor(x,map=TRUE,save.map=TRUE) #Não cria o mapa(s), mas salva no diretório.
     
     
     
     